改造 admin-template 项目：集成 Electron 桌面端
概述
在现有的 admin-template Web 项目基础上，添加 Electron 桌面端外壳，实现 Web 应用到桌面应用的转换。本节涵盖依赖安装、主进程配置、Vite 条件构建和路由适配等关键步骤。
依赖安装
# 安装 Electron 相关 Vite 插件
pnpm add -D vite-plugin-electron vite-plugin-electron-renderer
# 安装 Electron（指定版本 27，因 28 暂不支持 ESM 模式）
pnpm add -D electron@27
bash
注意：Electron 28 在某些环境下可能不支持 ES Module 模式，建议使用 Electron 27 确保稳定性。
目录结构
admin-template/
├── electron/ # 新增：Electron 主进程
│ ├── main.ts # 主进程入口
│ └── preload.ts # 预加载脚本
├── src/ # 渲染进程（Vue 应用）
├── vite.config.ts # 需修改：条件加载 Electron 插件
└── package.json # 需修改：添加 Electron 脚本
text
主进程配置
// electron/main.ts
import { app, BrowserWindow } from 'electron'
import path from 'node:path'
app.whenReady().then(() => {
const win = new BrowserWindow({
width: 1200,
height: 800,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
},
})
// 开发模式：加载 Vite 开发服务器
if (process.env.NODE_ENV === 'development') {
win.loadURL('http://localhost:5173')
win.webContents.openDevTools()
} else {
// 生产模式：加载构建产物
win.loadFile(path.join(__dirname, '../dist/index.html'))
}
})
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
typescript
Vite 配置修改
条件加载 Electron 插件
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import electron from 'vite-plugin-electron'
import UnoCSS from 'unocss/vite'
const isElectron = process.env.ELECTRON === 'true'
export default defineConfig({
plugins: [
vue(),
UnoCSS(),
// 仅在 Electron 模式下加载
isElectron && electron([
{ entry: 'electron/main.ts' },
{ entry: 'electron/preload.ts' },
]),
// Electron 模式下不需要的插件
!isElectron && cdnPlugin(),
!isElectron && pwaPlugin(),
!isElectron && mockPlugin(),
].filter(Boolean),
})
typescript
环境变量控制
// 通过环境变量判断是否为 Electron 模式
const isElectron = process.env.ELECTRON === 'true'
// Electron 不需要的插件列表
const webOnlyPlugins = [cdnPlugin, pwaPlugin, mockPlugin]
// 条件加载
const plugins = [
vue(),
UnoCSS(),
...(isElectron ? [electron(...)] : webOnlyPlugins.map(p => p())),
]
typescript
关键注意事项
1. 生产模式 base 路径
// vite.config.ts
export default defineConfig({
base: isElectron ? './' : '/', // Electron 使用相对路径
})
typescript
2. 路由模式适配
// router/index.ts
import { createRouter, createWebHashHistory } from 'vue-router'
// Electron 中必须使用 Hash 模式
const router = createRouter({
history: createWebHashHistory(),
routes: [...],
})
typescript
3. package.json 脚本
{
"scripts": {
"dev": "vite",
"dev:electron": "ELECTRON=true vite",
"build": "vite build",
"build:electron": "ELECTRON=true vite build && electron-builder"
}
}
json
Electron vs Web 模式配置差异
| 配置项 | Web 模式 | Electron 模式 |
|---|---|---|
base | / | ./ |
| 路由模式 | createWebHistory | createWebHashHistory |
| CDN 插件 | 启用 | 禁用 |
| PWA 插件 | 启用 | 禁用 |
| Mock 插件 | 启用 | 禁用 |
| 输出目标 | 浏览器 | Electron Renderer |
实践要点
- Electron 构建时不需要 CDN、PWA 和 Mock 插件，通过环境变量做条件加载
- 生产模式的
base路径必须改为相对路径（./），否则资源加载失败 - 路由必须使用 Hash 模式，因为 Electron 的
file://协议不支持 History 模式 package.json中可以通过ELECTRON=true环境变量控制构建行为- 改造完成后，分别在 Web 模式和 Electron 模式下测试功能一致性
↑